SAML Authentication

Security Assertion Markup Language (SAML) is an open standard that enables the exchange of security credentials between an identity provider and a service provider. This enables single sign-on, allowing the use of one set of credentials (for each user) to login to many different websites and web services. SAML is generally used to increase security and enhance user experience.

SAML can be used as the authentication provider in Pyramid. Start by selecting SAML as the authentication provider in the Admin console, and then define the SAML Settings and Initial User.

  • Click here to see a specific guide for setting up ADFS SAML
  • Click here to see a specific guide for setting up Azure SAML

Pyramid also supports integration with other SAML vendors, such as Ping and OKTA.

Note: This feature is available with Enterprise licensing only.

Important: If Same Site client security is set to Strict when using SAML authentication, this may cause a loop redirect between Pyramid and the SAML provider, as cookies are prevented from working across different web domains.

SAML Flow

Each user must login once to the single sign-on with the identity provider. When the user tries to access the service provider, it sends an authorization and authentication request to the identity provider. The identity provider checks the user's credentials and determines whether the user is authorized to access the required service. If the user is authorized, it sends a SAML assertion (an XML document) from the service provider, with the authorization and authentication messages.

SAML Setup

  1. From the Admin Console, click Security > Authentication (purple arrow).

    2. This opens the Authentication page in the Admin Console. (See below.)

  2. From the Provider drop-down, select SAML.

    3. This identifies SAML as the authentication provider.

  3. From the Vendor drop-down, select your SAML vendor. The available options are Unspecified, Ping, Azure, Okta, ADFS, AWS, Google, and Generic.

    4. Select Generic if you are using a SAML vendor that is not available from the drop-down. Note: Selecting an option from this drop-down affects the fields that are available on this page.

  4. Define the Provider settings, Certificate, Initial user settings (including principal name), and any other options given your selected vendor.

    5. See the following sections for more information. Note: The SAML Settings section may be sub-divided into further collapsible sections, for example, the Ping vendor includes both Provider Settings (orange highlight) and Signature Settings.

  5. Once you are happy with your settings do one of the following:

    • Click Save to update the current settings.
    • Click Apply to change vendor / provider completely. This action will delete or disable all users.

  6. Once SAML authentication is configured, access to Pyramid can be completed through a SAML token exchange with the designated SAML provider.

You need to register your Pyramid implementation with the SAML provider to generate all the keys, tokens, and access points to allow the authentication to operate.

Authentication Provider fields

  • Provider: The provider that you want to use. In this case, SAML. For other providers, see Authentication
  • Vendor: The SAML vendor. Available options are:
    • Unspecified
    • Ping
    • Azure
    • Okta
    • ADFS - Connect to Active Directory Federation Services (ADFS).
    • AWS
    • Google
    • Generic - This option is used where you are using a SAML vendor that is not available from the drop-down.

Provider Settings

Required for Vendors: All

  • Remove Auth Context Enforcement
  • Enable Windows authentication: (ADFS only.) Select this checkbox to indicate that Windows Authentication is enabled for Active Directory.
  • Consumer URL: This will be the Pyramid web site address that will be "called" back by the SAML provider. Typically this should be "https://myPyramidSite.com."
  • SAML Issuer: The access token or identifier provided from the SAML provider to confirm the incoming application is Pyramid.
  • IDP URL: The SAML provider's URL address - effectively the destination where the SAML request must be sent.
  • Logout URL: The URL that the user is redirected to after successfully signing out of Pyramid.

Certificate

The (Base64) certificate is a signed certificate provided by the SAML provider to allow Pyramid to decrypt the assertion messages coming in from the IDP. The certificate is provided by the SAML provider itself. This is CRITICAL.

Signature Settings

If your SAML Vendor is Ping (formerly ForgeRock) you can sign your outgoing requests. To do so, you need to enable the functionality and supply details of an active signing certificate and private key:

  • Sign outgoing requests: Enable and disable outgoing request signing.
  • Supply details of the signing key and certificate pair:
    • Signing Certificate: Paste the signing certificate for Ping. This is a Base64 certificate in the PEM format
    • Signing Private Key: Paste the private key for Ping. This is an RSA Key with a length of 2048-bits.

Initial User

Required for Vendors: All

This is the initial master user (from the SAML framework) that will be matched in Pyramid:

  • User Name: The internal user name of the initial user. This is a bypass for the user when working outside of SAML.
  • First Name: The first name of the initial user.
  • Last Name: The last name of the initial user.
  • Email: The email of the initial user.
  • Principal Name: The SAML login ID of the initial user typically in the format someone@domain.com. This is the critical element that will enable Pyramid to match the incoming SAML assertion with the user account.
  • Password: The internal password for the user. Only used if manually logging in without the SAML framework.

    • Tip: To login manually, you can use the /login/login.html or just /login entrypoints.